- Register evmigration interfaces in the default tx config so
  MsgClaimLegacyAccount / MsgMigrateValidator can be encoded and signed.
- Add ClaimLegacyAccountTx / MigrateValidatorTx helpers plus
  NewMsgClaimLegacyAccount / NewMsgMigrateValidator constructors and
  MigrationResult on EVMigrationClient.
- Add EVMAddressFromKey to derive a 0x EIP-55 address for
  eth_secp256k1 keys; promote go-ethereum to a direct dependency.

Wire up x/erc20, x/feemarket, x/precisebank, and x/vm RegisterInterfaces
so SDK consumers can encode and sign EVM-module messages (e.g.
MsgConvertERC20, MsgEthereumTx) through the standard tx pipeline.

Pulls a handful of new indirect deps via go mod tidy.

bufconn-backed fake QueryServer exercises Params, MigrationRecord,
MigrationRecordByNewAddress, MigrationEstimate, and MigrationStats,
plus a NotFound path. Adds sanity checks for the new
NewMsgClaimLegacyAccount / NewMsgMigrateValidator constructors.

- Document EVMigration query + tx helpers and MigrationResult.
- Note expanded BuildAndSignTx surface (Options, Prepare/Sign split,
  BroadcastAndWait, GetTxsByEvents).
- Document EVMAddressFromKey and the EVM-module interface registrations
  in NewDefaultTxConfig.
- Add a tutorial for the legacy account / validator migration flow.

Sketches the opinionated client layout for x/vm, x/erc20, x/feemarket,
and x/precisebank, plus Ethereum signing helpers in pkg/crypto, config
additions for EVMChainID/EVMDenom, and a phased build sequence. No
code changes.

Anchor decisions in lumera/docs/evm-integration:

- Note the shared nonce/sequence counter and its impact on nonce caching.
- Default EVMDenom to alume; add EVMValueUnit and Wei/ULume helpers for
  the 6 <-> 18 decimal boundary (precisebank, 10^12 factor).
- Tighten Bech32ToEVM contract: reject legacy secp256k1 cosmos addresses
  whose derivation is not reversible.
- Set GasTipCap default from feemarket.Params.MinGasPrice and call out
  the ExtensionOptionsEthereumTx routing on Lumera's dual-route ante.
- New pkg/evm/precompiles section covering Lumera's custom precompiles
  (action 0x0901, supernode 0x0902, wasm 0x0903) plus standard
  precompile address constants.
- Expand build sequence to a dedicated precompiles phase; add open
  questions on the precompile-vs-msg choice rule, Lumera defaults
  option group, and ABI vendoring strategy.

- ethaddr.go: EVMToBech32 / Bech32ToEVM for byte-level encoding plus
  Wei / ULume / ULumeDecToWei to bridge the 6 <-> 18 decimal boundary
  defined by x/precisebank (10^12 factor).
- ethsign.go: SignEthereumTx signs a go-ethereum tx using the keyring's
  eth_secp256k1 key and the latest EIP-155 signer for the EVM chain ID.
  WrapAsMsgEthereumTx packages a signed tx as MsgEthereumTx; RecoverSender
  exposes the recovered address for verification.

Round-trip tests cover sign -> recover, MsgEthereumTx wrap, rejection of
cosmos secp256k1 keys, decimal conversions, and bech32 length guards.

Phase 1 of docs/design/0001-cosmos-evm-api.md.

- EVMClient (x/vm): Code, Storage, Balance (alume), EthAccount,
  CosmosAccount, Params, BaseFee, Config, GlobalMinGasPrice, EthCall,
  EstimateGas, TraceTx. EthCall/EstimateGas marshal TransactionArgs JSON
  for the cosmos/evm gRPC contract.
- FeeMarketClient (x/feemarket): Params, BaseFee (ulume decimal),
  BlockGas. Companion to EVMClient.BaseFee which returns alume.
- PreciseBankClient (x/precisebank): Remainder, FractionalBalance.
- All three wired onto blockchain.Client via the existing constructor.

Tests stub the QueryClient interface directly instead of going through
bufconn, because the default grpc proto v2 codec panics on gogoproto
customtype fields (sdkmath.Int / LegacyDec) in EVM responses. Tests
cover Lumera-flavored defaults (BaseFee 0.0025 ulume/gas, etc).

Phase 2 of docs/design/0001-cosmos-evm-api.md.

EVMClient gains tx helpers signed with the keyring's eth_secp256k1 key
and routed through Cosmos EVM's MsgEthereumTx + ExtensionOptionsEthereumTx
envelope:

- SendEthereumTransaction: resolves nonce (EthAccount), gas (EstimateGas
  + 20% buffer), tip/fee caps (feemarket MinGasPrice and BaseFee*2+tip),
  signs the DynamicFeeTx (EIP-1559), wraps as MsgEthereumTx, and
  broadcasts via the base client.
- DeployContract: contract creation sugar; returns the CREATE address
  derived from sender+nonce.
- CallContract: read-only EthCall sugar.
- RawEthereumTx: broadcast a pre-signed go-ethereum tx unchanged
  (hardware wallet path).
- buildEthereumTxBytes: shared envelope encoder (callable from tests).

Configuration additions plumbed end-to-end:

- blockchain/base/Config gains EVMChainID, EVMNativeDenom (ulume),
  EVMExtendedDenom (alume), EVMGasTipCap, EVMGasFeeCap.
- client/config mirrors them; client.WithEVMChainID / WithEVMNativeDenom /
  WithEVMExtendedDenom / WithEVMGasCaps expose them via Option.
- client.New copies the EVM fields into blockchain.Config.

Guards:

- validateTxBuildOptions rejects MsgEthereumTx in the cosmos signing
  pipeline so callers cannot accidentally double-sign.
- SendEthereumTransaction / RawEthereumTx error when EVMClient lacks a
  Client backref or EVMChainID is unset.

Tests cover envelope round-trip via the standard TxDecoder, the CREATE
address derivation, and the new guards. Phase 3 of
docs/design/0001-cosmos-evm-api.md.

- ERC20Client (x/erc20): TokenPairs (paginated), TokenPair, Params plus
  message constructors NewMsgConvertCoin / NewMsgConvertERC20 /
  NewMsgRegisterERC20 / NewMsgToggleConversion.
- Tx helpers on blockchain.Client: ConvertCoinToERC20 (cosmos coin ->
  ERC20, signed via the bech32 sender derived from the keyring) and
  ConvertERC20ToCoin (ERC20 -> cosmos coin, signed via the 0x sender
  derived from eth_secp256k1). Plus RegisterERC20Tx and
  ToggleConversionTx for governance flows. All four use the standard
  cosmos signing pipeline (BuildAndSignTx) — no Ethereum signing.
- ConversionResult result type and broadcastConversion shared helper.
- ABI sugar (erc20_abi.go): hand-rolled minimal ERC20 JSON (balanceOf,
  totalSupply, allowance, name, symbol, decimals) compiled at init.
  Erc20Balance / Erc20TotalSupply / Erc20Allowance / Erc20Metadata pack
  calldata and route through EVMClient.CallContract.

Tests cover queries, message constructors, and ABI pack/unpack.
Phase 4 of docs/design/0001-cosmos-evm-api.md.

- pkg/evm/precompiles exposes vendored Hardhat artifact ABIs (action,
  supernode, wasm) via go:embed and parses them at init. Also exports
  Lumera custom precompile addresses (0x0901 / 0x0902 / 0x0903) and the
  eight standard cosmos/evm precompile addresses as named constants.
  Generic PackCall / UnpackReturn helpers wrap the go-ethereum abi
  package.
- blockchain.PrecompileClient: a single generic wrapper that holds a
  precompile address + parsed ABI and routes calls through EVMClient.
  Call(ctx, method, args...) does a read-only EthCall and unpacks the
  outputs; Send(ctx, method, opts, args...) signs and broadcasts a
  state-changing call via SendEthereumTransaction.
- EVMClient grows Action / Supernode / Wasm fields wired at construction
  to the corresponding precompile addresses + ABIs. Callers invoke any
  method on any precompile without compiling Solidity bindings.

ABI artifacts are Hardhat-format JSON with an `abi` field; the loader
falls back to a bare array if a vendor switches formats later. Tests
verify the embedded ABIs parse, exposed method names match the docs,
and the PrecompileClient guards against missing backref / unknown
method.

Phase 5 of docs/design/0001-cosmos-evm-api.md. Typed wrappers for
specific methods (RequestCascade, RegisterSupernode, etc.) are out of
scope for v1 — callers compose them with PackCall and the published ABI.

- API.md gains entries for EVMClient / ERC20Client / FeeMarketClient /
  PreciseBankClient and the pkg/evm/precompiles package, plus new
  client.WithEVM* options.
- DEVELOPER_GUIDE.md adds tutorials 8-10:
  - Sending an Ethereum-format transaction (configuration + Wei helper).
  - ERC20 conversion (ConvertCoinToERC20 + Erc20Balance ABI sugar).
  - Invoking a Lumera precompile via the generic Call/Send wrappers.
  Existing tutorials renumbered (SuperNodes is now 11).
- examples/evm-transfer is a runnable CLI that signs and broadcasts an
  EIP-1559 transfer using an eth_secp256k1 key, prints the eth tx hash,
  cosmos tx hash, height, and gas used.

Phase 6 of docs/design/0001-cosmos-evm-api.md. Phase 7 (EIP-712,
nonce tracker, fee-market cache) remains.

- DeployContract: resolve and pin the nonce before broadcast and derive
  the CREATE address from it directly. Eliminates the race in the old
  post-broadcast EthAccount.Nonce-1 path.
- resolveEVMDenoms: fall back to querying x/vm Params for native and
  extended denoms when Config leaves them empty.
- resolveMinGasTipCap: pull the default tip cap from
  feemarket.Params.MinGasPrice (ulume decimal) and scale to alume via
  ULumeDecToWei, instead of GlobalMinGasPrice.
- buildEthereumTxBytes: require a non-empty extended denom; falling back
  to the native denom silently produced wrong-denom fees.
- Tighten ABI tests: wasm.execute is phase-1 non-payable,
  supernode.registerSupernode keeps bech32 string args, action fees stay
  uint256. Plus tests for the new gas-cap and denom-fallback paths.
- Docstring polish in base/Config and ethsign.WrapAsMsgEthereumTx.

- DEVELOPER_GUIDE.md is now a one-page index that points to topical
  guides under docs/guides/.
- Split into six self-contained sections:
    getting-started.md  install, config, factory, troubleshooting
    crypto.md           keyring, key types, address derivation, eth signing
    actions.md          x/action + x/supernode queries and tx helpers
    cascade.md          upload/download/events/stepwise flow
    ica.md              ICA controller + lower-level packet helpers
    evm.md              x/vm, x/erc20, x/feemarket, x/precisebank,
                        custom precompiles, x/evmigration
- API.md gains a topic-to-guide quick-link table at the top.

New examples for the EVM surface:

- examples/evm-balance     read-only: balance (alume + ulume), nonce,
                           base fee, min gas price, precisebank fractional.
- examples/erc20-convert   ConvertCoinToERC20 / ConvertERC20ToCoin both
                           directions, optionally prints the post-tx
                           ERC20 balance via the ABI sugar.
- examples/precompile-action  invokes the action precompile (0x0901) for
                              both read (getParams) and write (approveAction).

`go test ./...` is green; all four EVM-era examples compile under `go build`.

- Comment out local supernode replace in go.mod so module consumers are
  not broken by a path-based replace directive.
- Replace int64(gas) cast in resolveFeeAmount with sdkmath.NewIntFromUint64
  to avoid signed overflow when callers pass a large user-controlled
  GasLimit via TxBuildOptions.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>